Update documentation post-PR #298 merge #388

ViktorCVS · 2025-06-07T16:30:49Z

Documentation PR post-PR #298 merge

Clarify and expand migration instructions now that pull request ros-controls#298 has been merged, ensuring users know how to adjust their configurations accordingly.

ViktorCVS · 2025-06-07T16:38:17Z

@christophfroehlich I’ve created a PR to update the documentation, but I’m not sure if there are other repositories or files I need to update. Can you help me with that?

codecov-commenter · 2025-06-07T16:41:51Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 78.38%. Comparing base (a422c48) to head (aa9ae64).

Additional details and impacted files

@@             Coverage Diff              @@
##           ros2-master     #388   +/-   ##
============================================
  Coverage        78.38%   78.38%           
============================================
  Files               30       30           
  Lines             1888     1888           
  Branches           114      114           
============================================
  Hits              1480     1480           
  Misses             338      338           
  Partials            70       70

Flag	Coverage Δ
unittests	`78.38% <ø> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

christophfroehlich · 2025-06-07T19:40:39Z

@christophfroehlich I’ve created a PR to update the documentation, but I’m not sure if there are other repositories or files I need to update. Can you help me with that?

I suggest that you add the documentation here
https://github.com/ros-controls/control_toolbox/blob/ros2-master/doc/control_toolbox.md
which will be published here
https://control.ros.org/rolling/doc/control_toolbox/doc/index.html

Add a new section for the PID, copy basis information from the docstring and add your antiwindup description from the other PR there.

Adds a comprehensive PID section to control_toolbox.md, covering the standard PID equation, descriptions of proportional, integral, and derivative gains, output limits, detailed explanations of anti-windup strategies (back-calculation and conditional integration) with update rules and default values, and a C++ usage example.

Clarify and expand migration instructions now that pull request ros-controls#298 has been merged, ensuring users know how to adjust their configurations accordingly.

ViktorCVS · 2025-06-13T13:42:33Z

@christophfroehlich I’ve created a PR to update the documentation, but I’m not sure if there are other repositories or files I need to update. Can you help me with that?

I suggest that you add the documentation here https://github.com/ros-controls/control_toolbox/blob/ros2-master/doc/control_toolbox.md which will be published here https://control.ros.org/rolling/doc/control_toolbox/doc/index.html

Add a new section for the PID, copy basis information from the docstring and add your antiwindup description from the other PR there.

Done! I changed it from draft to open. If there is still documentation to add, I’ll add more commits.

Adds a comprehensive PID section to control_toolbox.md, covering the standard PID equation, descriptions of proportional, integral, and derivative gains, output limits, detailed explanations of anti-windup strategies (back-calculation and conditional integration) with update rules and default values, and a C++ usage example.

christophfroehlich

Thanks for this addition. Some details got outdated, comments see below.

please update also the docstring of the Pid Class in pid.hpp accordingly (remove i_clamp etc).

control_toolbox/control_toolbox/include/control_toolbox/pid.hpp

Line 205 in b2b3425

/*! \class Pid

And could you please also add the references to literature?

christophfroehlich · 2025-06-23T20:40:16Z

doc/migration.rst

+
+Pid/PidRos
+***********************************************************
+* The parameters :paramref:`antiwindup`, :paramref:`i_clamp_max`, and :paramref:`i_clamp_min` have been removed. The anti-windup behavior is now configured via the :paramref:`AntiwindupStrategy` enum. (`#298 <https://github.com/ros-controls/control_toolbox/pull/298>`_).


Suggested change

* The parameters :paramref:`antiwindup`, :paramref:`i_clamp_max`, and :paramref:`i_clamp_min` have been removed. The anti-windup behavior is now configured via the :paramref:`AntiwindupStrategy` enum. (`#298 <https://github.com/ros-controls/control_toolbox/pull/298>`_).

* The parameters :paramref:`antiwindup`, :paramref:`i_clamp_max`, and :paramref:`i_clamp_min` have been removed. The anti-windup behavior is now configured via the :paramref:`AntiWindupStrategy` enum. (`#298 <https://github.com/ros-controls/control_toolbox/pull/298>`_).

christophfroehlich · 2025-06-23T20:43:23Z

doc/control_toolbox.md

+
+## PID Controller
+
+The PID (Proportional-Integral-Derivative) controller is a widely used feedback control loop mechanism that calculates an "error" value as the difference between a measured process variable and a desired setpoint. The controller attempts to minimize the error by adjusting the process control inputs. This class implements a generic structure that can be used to create a wide range of PID controllers. It can function independently or be subclassed to provide more specific controls based on a particular control loop.


Suggested change

The PID (Proportional-Integral-Derivative) controller is a widely used feedback control loop mechanism that calculates an "error" value as the difference between a measured process variable and a desired setpoint. The controller attempts to minimize the error by adjusting the process control inputs. This class implements a generic structure that can be used to create a wide range of PID controllers. It can function independently or be subclassed to provide more specific controls based on a particular control loop.

The PID (Proportional-Integral-Derivative) controller is a widely used feedback controller. This class implements a generic structure that can be used to create a wide range of PID controllers. It can function independently or be subclassed to provide more specific controls based on a particular control loop.

We don't have to repeat control theory here ;)

christophfroehlich · 2025-06-23T20:47:11Z

doc/control_toolbox.md

+* d<sub>term</sub> = d<sub>gain</sub> * d<sub>error</sub>
+
+and:
+* error = desired_state - actual_state


Suggested change

* error = desired_state - actual_state

* error = desired_state - measured_state

christophfroehlich · 2025-06-23T20:49:57Z

doc/control_toolbox.md

+*   `i` (Integral gain): This gain determines the reaction based on the sum of recent errors. The integral term accounts for past values of the error and integrates them over time to produce the `i_term`. This helps in eliminating steady-state errors.
+*   `d` (Derivative gain): This gain determines the reaction based on the rate at which the error has been changing. The derivative term predicts future errors based on the rate of change of the current error. This helps in reducing overshoot, settling time, and other transient performance variables.
+*   `u_clamp` (Minimum and maximum bounds for the controller output): These bounds are applied to the final command output of the controller, ensuring the output stays within acceptable physical limits.
+*   `trk_tc` (Tracking time constant): This parameter is specific to the 'back_calculation' anti-windup strategy. If set to 0.0 when this strategy is selected, a recommended default value will be applied.


Suggested change

* `trk_tc` (Tracking time constant): This parameter is specific to the 'back_calculation' anti-windup strategy. If set to 0.0 when this strategy is selected, a recommended default value will be applied.

* `tracking_time_constant` (Tracking time constant): This parameter is specific to the 'back_calculation' anti-windup strategy. If set to 0.0 when this strategy is selected, a recommended default value will be applied.

christophfroehlich · 2025-06-23T20:52:03Z

doc/control_toolbox.md

+*   `trk_tc` (Tracking time constant): This parameter is specific to the 'back_calculation' anti-windup strategy. If set to 0.0 when this strategy is selected, a recommended default value will be applied.
+*   `antiwindup_strat` (Anti-windup strategy): This parameter selects how the integrator is prevented from winding up when the controller output saturates. Available options are:
+    *   `NONE`: no anti-windup technique; the integral term accumulates without correction.
+    *   `BACK_CALCULATION`: adjusts the integral term based on the difference between the unsaturated and saturated outputs using the tracking time constant `trk_tc`. Faster correction for smaller `trk_tc`.


Suggested change

* `BACK_CALCULATION`: adjusts the integral term based on the difference between the unsaturated and saturated outputs using the tracking time constant `trk_tc`. Faster correction for smaller `trk_tc`.

* `BACK_CALCULATION`: adjusts the integral term based on the difference between the unsaturated and saturated outputs using the tracking time constant `tracking_time_constant`. Faster correction for smaller `tracking_time_constant`.

christophfroehlich · 2025-06-23T20:52:27Z

doc/control_toolbox.md

+
+Anti-windup functionality is crucial for PID controllers, especially when the control output is subject to saturation (clamping). Without anti-windup, the integral term can accumulate excessively when the controller output is saturated, leading to large overshoots and sluggish response once the error changes direction. The `control_toolbox::Pid` class offers two anti-windup strategies:
+
+*   **`BACK_CALCULATION`**: This strategy adjusts the integral term based on the difference between the saturated and unsaturated controller output. When the controller output `command` exceeds the output limits (`u_max` or `u_min`), the integral term `i_term` is adjusted by subtracting a value proportional to the difference between the saturated output `command_sat` and the unsaturated output `command`. This prevents the integral term from accumulating beyond what is necessary to maintain the output at its saturation limit. The `tracking_time_constant` (`trk_tc`) parameter is used to tune the speed of this adjustment. A smaller `trk_tc` results in faster anti-windup action.


Suggested change

* **`BACK_CALCULATION`**: This strategy adjusts the integral term based on the difference between the saturated and unsaturated controller output. When the controller output `command` exceeds the output limits (`u_max` or `u_min`), the integral term `i_term` is adjusted by subtracting a value proportional to the difference between the saturated output `command_sat` and the unsaturated output `command`. This prevents the integral term from accumulating beyond what is necessary to maintain the output at its saturation limit. The `tracking_time_constant` (`trk_tc`) parameter is used to tune the speed of this adjustment. A smaller `trk_tc` results in faster anti-windup action.

* **`BACK_CALCULATION`**: This strategy adjusts the integral term based on the difference between the saturated and unsaturated controller output. When the controller output `command` exceeds the output limits (`u_max` or `u_min`), the integral term `i_term` is adjusted by subtracting a value proportional to the difference between the saturated output `command_sat` and the unsaturated output `command`. This prevents the integral term from accumulating beyond what is necessary to maintain the output at its saturation limit. The `tracking_time_constant` parameter is used to tune the speed of this adjustment. A smaller value results in faster anti-windup action.

christophfroehlich · 2025-06-23T20:53:03Z

doc/control_toolbox.md

+
+    i<sub>term</sub> += dt * (i<sub>gain</sub> * error + (1 / trk<sub>tc</sub>) * (command<sub>sat</sub> - command))
+
+    If `trk_tc` is set to 0.0, a default value is calculated based on the proportional and derivative gains:


Suggested change

If `trk_tc` is set to 0.0, a default value is calculated based on the proportional and derivative gains:

If `trk_tc`, i.e., `tracking_time_constant` parameter, is set to 0.0, a default value is calculated based on the proportional and derivative gains:

Refresh migration notes post-PR ros-controls#298 merge

aeafdcf

Clarify and expand migration instructions now that pull request ros-controls#298 has been merged, ensuring users know how to adjust their configurations accordingly.

ViktorCVS and others added 3 commits June 12, 2025 10:31

Merge branch 'ros2-master' into pr/documentation

555f620

Refresh migration notes post-PR ros-controls#298 merge

f6e6c48

Clarify and expand migration instructions now that pull request ros-controls#298 has been merged, ensuring users know how to adjust their configurations accordingly.

ViktorCVS marked this pull request as ready for review June 13, 2025 13:40

github-actions bot requested review from anfemosa, aprotyas, ARK3r, destogl, livanov93, moriarty and saikishor June 13, 2025 13:42

ViktorCVS and others added 2 commits June 13, 2025 13:55

Merge branch 'ros2-master' into pr/documentation

dd9cb03

christophfroehlich requested review from christophfroehlich June 18, 2025 08:44

Merge branch 'ros2-master' into pr/documentation

aa9ae64

christophfroehlich requested changes Jun 23, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Update documentation post-PR #298 merge #388

Update documentation post-PR #298 merge #388

Uh oh!

ViktorCVS commented Jun 7, 2025

Uh oh!

ViktorCVS commented Jun 7, 2025

Uh oh!

codecov-commenter commented Jun 7, 2025 •

edited

Loading

Uh oh!

christophfroehlich commented Jun 7, 2025

Uh oh!

ViktorCVS commented Jun 13, 2025

Uh oh!

christophfroehlich left a comment

Uh oh!

christophfroehlich Jun 23, 2025

Uh oh!

christophfroehlich Jun 23, 2025

Uh oh!

christophfroehlich Jun 23, 2025

Uh oh!

christophfroehlich Jun 23, 2025

Uh oh!

christophfroehlich Jun 23, 2025

Uh oh!

christophfroehlich Jun 23, 2025

Uh oh!

christophfroehlich Jun 23, 2025

Uh oh!

Uh oh!

	* The parameters :paramref:`antiwindup`, :paramref:`i_clamp_max`, and :paramref:`i_clamp_min` have been removed. The anti-windup behavior is now configured via the :paramref:`AntiwindupStrategy` enum. (`#298 <https://github.com/ros-controls/control_toolbox/pull/298>`_).
	* The parameters :paramref:`antiwindup`, :paramref:`i_clamp_max`, and :paramref:`i_clamp_min` have been removed. The anti-windup behavior is now configured via the :paramref:`AntiWindupStrategy` enum. (`#298 <https://github.com/ros-controls/control_toolbox/pull/298>`_).


		## PID Controller

		The PID (Proportional-Integral-Derivative) controller is a widely used feedback control loop mechanism that calculates an "error" value as the difference between a measured process variable and a desired setpoint. The controller attempts to minimize the error by adjusting the process control inputs. This class implements a generic structure that can be used to create a wide range of PID controllers. It can function independently or be subclassed to provide more specific controls based on a particular control loop.

	* error = desired_state - actual_state
	* error = desired_state - measured_state

	* `trk_tc` (Tracking time constant): This parameter is specific to the 'back_calculation' anti-windup strategy. If set to 0.0 when this strategy is selected, a recommended default value will be applied.
	* `tracking_time_constant` (Tracking time constant): This parameter is specific to the 'back_calculation' anti-windup strategy. If set to 0.0 when this strategy is selected, a recommended default value will be applied.

	* `BACK_CALCULATION`: adjusts the integral term based on the difference between the unsaturated and saturated outputs using the tracking time constant `trk_tc`. Faster correction for smaller `trk_tc`.
	* `BACK_CALCULATION`: adjusts the integral term based on the difference between the unsaturated and saturated outputs using the tracking time constant `tracking_time_constant`. Faster correction for smaller `tracking_time_constant`.


		Anti-windup functionality is crucial for PID controllers, especially when the control output is subject to saturation (clamping). Without anti-windup, the integral term can accumulate excessively when the controller output is saturated, leading to large overshoots and sluggish response once the error changes direction. The `control_toolbox::Pid` class offers two anti-windup strategies:

		* `BACK_CALCULATION`: This strategy adjusts the integral term based on the difference between the saturated and unsaturated controller output. When the controller output `command` exceeds the output limits (`u_max` or `u_min`), the integral term `i_term` is adjusted by subtracting a value proportional to the difference between the saturated output `command_sat` and the unsaturated output `command`. This prevents the integral term from accumulating beyond what is necessary to maintain the output at its saturation limit. The `tracking_time_constant` (`trk_tc`) parameter is used to tune the speed of this adjustment. A smaller `trk_tc` results in faster anti-windup action.


		i<sub>term</sub> += dt * (i<sub>gain</sub> * error + (1 / trk<sub>tc</sub>) * (command<sub>sat</sub> - command))

		If `trk_tc` is set to 0.0, a default value is calculated based on the proportional and derivative gains:

	If `trk_tc` is set to 0.0, a default value is calculated based on the proportional and derivative gains:
	If `trk_tc`, i.e., `tracking_time_constant` parameter, is set to 0.0, a default value is calculated based on the proportional and derivative gains:

Update documentation post-PR #298 merge #388

Are you sure you want to change the base?

Update documentation post-PR #298 merge #388

Uh oh!

Conversation

ViktorCVS commented Jun 7, 2025

Uh oh!

ViktorCVS commented Jun 7, 2025

Uh oh!

codecov-commenter commented Jun 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

christophfroehlich commented Jun 7, 2025

Uh oh!

ViktorCVS commented Jun 13, 2025

Uh oh!

christophfroehlich left a comment

Choose a reason for hiding this comment

Uh oh!

christophfroehlich Jun 23, 2025

Choose a reason for hiding this comment

Uh oh!

christophfroehlich Jun 23, 2025

Choose a reason for hiding this comment

Uh oh!

christophfroehlich Jun 23, 2025

Choose a reason for hiding this comment

Uh oh!

christophfroehlich Jun 23, 2025

Choose a reason for hiding this comment

Uh oh!

christophfroehlich Jun 23, 2025

Choose a reason for hiding this comment

Uh oh!

christophfroehlich Jun 23, 2025

Choose a reason for hiding this comment

Uh oh!

christophfroehlich Jun 23, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

codecov-commenter commented Jun 7, 2025 •

edited

Loading